--------------------------------------------------------------------------------
---  HIGHLIGHT MANUAL (W32 GUI) - Version 2.2-8 -------------- FEBRUARY 2005 ---
--------------------------------------------------------------------------------

OSI Certified Open Source Software


Highlight converts sourcecode to HTML, XHTML, RTF, LaTeX, TeX, XSL-FO and XML 
files with syntax highlighting. Its language definitions, colour themes and
indentation schemes are customizable.


CONTENT:
--------------------------------------------------------------------------------

1. Platforms
2. Supported programming/markup languages
3. Features
4. Highlight file format
5. Defining new language definitions
6. Defining new colour themes
7. Defining new indentation schemes
8. Windows Explorer integration
9. Contact


1. PLATFORMS:
--------------------------------------------------------------------------------

Highlight is written in C++. There exist three versions of Highlight:
- UNIX console application
- Win32 console application
- Win32 GUI application

For other platforms, see the highlight homepage. The source package is known to
compile with gcc3.x, MS Visual .NET, and MW Codewarrior 8.


2. SUPPORTED PROGRAMMING / MARKUP LANGUAGES:
--------------------------------------------------------------------------------

Currently, Highlight supports the following programming languages, markup
languages and configuration files:

Action Script, ADA 95, Agda, AMPL, Aspect, Assembler, Amtrix, Avenue, (G)AWK,
Bash, BlitzBasic, BibTex, BMS, C, C++, C#, ClearBasic, Clipper, Cobol, Coldfusion
MX, CSS, DOS-Batch, Eiffel, Erlang, Euphoria, Express, Felix, Fortran, Frink,
Haskell, HTML, httpd.conf, Icon, IDL, INI, IO, Jasmin, Java, JavaScript, JSP,
LaTeX, LDIF, Lisp, Lotos, Lotus Script, Lua, Make,Maya, Matlab, Maple, Modelica,
Modula 3, Nasal, OCaml, (Object) Pascal, Objective C, Paradox, PATROL, Perl,
PHP, Pike, PL/1, PL/SQL, PostScript, POV Ray, Progress, Prolog, Python, Relax
NG Compact, Rexx, RPM Spec, Ruby, Small, SML, SNMPv2, Spin, Squirrel, Sybase, 
VHDL, Visual Basic, XML.


3. FEATURES:
--------------------------------------------------------------------------------

- highlighting of keywords, types, strings, numbers, escape sequences, comments,
  symbols and directive lines
- highlighting of custom keyword classes
- coloured output in HTML, XHTML 1.1, RTF, TeX, LaTeX, XSL-FO and XML format
- customizable reformatting and indentation of C, C++, C# and Java source code
- wrapping of long lines
- output of line numbers
- choice to embed the CSS-definitions in the output (X)HTML file or to save them
  in a separate CSS-file
- 50 colour themes
- conversion of plain text to a given output format without highlighting


4. HIGHLIGHT FILE FORMAT
--------------------------------------------------------------------------------

All Highlight configuration files are stored in plain ASCII text files. The
format is simple:

$ParamName=ParamValue

ParamName is the identifier of the parameter, ParamValue is its value.
The parameter names are not case sensitive.
The value may be a single character or a list of words. Lists may be split in
multiple lines.

Comments start with # as the first character in a line.


5. DEFINING NEW LANGUAGE DEFINITIONS:
--------------------------------------------------------------------------------

A language definition is a text file, where keywords and symbols of a program-
ming language are assigned to several categories.
Save the new file in the highlight directory/langDefs* with the following name:

<usual extension of sourcecode files>.lang

Examples: PHP -> php.lang, Java -> java.lang

If there exist multiple suffixes, list them in extensions.conf*.

FILE FORMAT:

# List of keywords; <class> is the name of the keyword class
# The class must be defined in the applied colour theme to provide a matching
# highlighting style
$KW_LIST(<class>)=<List>

# Prefix which determines keywords
# The class must be defined in the applied colour theme to provide a matching
# highlighting style
$KW_PREFIX(<class>)=<Character>

# Delimiters for keywords
# The class must be defined in the applied colour theme to provide a matching
# highlighting style
$KW_DELIM(<class>)=<open close>

# Tag open and close delimiters
# Tags are formatted like keywords of specified class
$TAG_DELIM(<class>)=<tag_open tag_close>

# List of String delimiters
$STRINGDELIMITERS=<List>

# List of escape characters in Strings (ie. "\")
$ESCCHAR=<List>

# Prefix which disables highlighting of escape characters
# within the following string
$RAWSTRINGPREFIX=<Character>

# Delimiters of multi-line comments
$ML_COMMENT=<comment_begin comment_close>

# List of strings which start single line comments
$SL_COMMENT=<List>

# Set true if single line comments have to start in first coloumn
$FL_COMMENT=<true / false>

# Opening string of preprocessor directive lines
$DIRECTIVE=<prefix>

# Set true if language source code may be reformatted (only C-style languages!)
$REFORMATTING=<true / false>

# Symbols which should be coloured (brackets, operators  etc)
$SYMBOLS=<List>

# List of special characters which may occour in keywords
$ALLOWEDCHARS=<character list>

# Set to true if multiple line comments may be nested
$ALLOWNESTEDCOMMENTS=false

# Set to true if programming language is not case sensitive
$IGNORECASE=<true / false>

# Include another language definition stored in the same data directory
$INCLUDE=<language definition>


Example:

#Content of pas.lang (Pascal/Objekt Pascal)

$KW_LIST(kwa)=true false if else then nil maxint case goto label and div downto in
mod not of or packed with do for do repeat while to until procedure function
program begin end const var type unit interface implementation uses private
public

$KW_LIST(kwb)=array boolean char integer file pointer real set string text record

$STRINGDELIMITERS=" '
$SL_COMMENT=//
$ML_COMMENT={ }
$IGNORECASE=true


6. DEFINING NEW THEME DEFINITIONS
--------------------------------------------------------------------------------

Colour themes are stored in plain ASCII files, defining the formatting of the
output. The RTF output ignores the background colour attribute. The files have
to be stored as *.style in the highlight directory/themes*. 

FILE FORMAT:

#<ColourAttr> = RR GG BB
#RR GG BB describes the red/green/blue hex-values which define the colour.
#(Value range: 00 (none) - FF (full))

#<FormatAttr> = <bold> <italic> <underline>
#Bold, italic und underline are optional attributes and may be combined.

# Colour of unrecognized text
$DEFAULTCOLOUR=RR GG BB

# Background colour (ignored by RTF)
$BGCOLOUR=RR GG BB

# Font size
$FONTSIZE=<number>

# Formatting of keywords, which belong to the corresponding keyword class
$KW_CLASS(<class>)=<ColourAttr> ( <FormatAttr> )

# Formatting of numbers
$NUMBER=<ColourAttr> ( <FormatAttr> )

# Formatting of escape characters
$ESCAPECHAR=<ColourAttr> ( <FormatAttr> )

# Formatting of strings
$STRING=<ColourAttr> ( <FormatAttr> )

# Formatting of strings within compiler directives
$STRING_DIRECTIVE=<ColourAttr> ( <FormatAttr> )

# Formatting of comments
$COMMENT=<ColourAttr> ( <FormatAttr> )

# Formatting of single line comments
$SL-COMMENT=<ColourAttr> ( <FormatAttr> )

# Formatting of compiler directives
$DIRECTIVE=<ColourAttr> ( <FormatAttr> )

# Formatting of symbols (optional, equals to $DEFAULTCOLOUR if omitted)
$SYMBOL=<ColourAttr> ( <FormatAttr> )

# Formatting of line numbers
$LINE=<ColourAttr> ( <FormatAttr> )


Example:

# Golden.style
$DEFAULTCOLOUR=dd bb 00
$BGCOLOUR=00 00 00
$FONTSIZE=10
$KW_CLASS(kwa)=dd bb 00 bold
$KW_CLASS(kwb)=dd bb 00
$NUMBER=ff ff ff
$ESCAPECHAR=ff 00 00
$STRING=ff 00 00
$STRING_DIRECTIVE=ff 00 00
$COMMENT=97 83 45 italic
$DIRECTIVE=ff dd aa
$LINE=97 83 45


7.  DEFINING NEW INDENTATION SCHEMES
--------------------------------------------------------------------------------

You can define custom indentation and formatting schemes. To enable reformatting
for your programming language, a $REFORMATTING=true switch has to be added to
the language definition. Note that the Artistic Style parser was designed to
only handle C-style languages (C++, Java, C#) correctly.
Indentation schemes are stored as *.indent in the highlight dir/indentSchemes*.

FILE FORMAT:

# Brackets handling:
# "break":  Break brackets from pre-block code (i.e. ANSI C/C++ style).
# "attach": Attach brackets to pre-block code (i.e. Java/K&R style).
# "linux":  Break definition-block brackets and attach command-block brackets.
# "break-closing-headers": Break brackets before closing headers (e.g. 'else',
#                          'catch', ..).  Should be appended to $brackets=attach
#                          or $brackets=linux.
$BRACKETS=<break | attach | linux | break-closing-headers>

# Insert empty lines around unrelated blocks, labels, classes, ...
# "true": default mode
# "all": also insert empty lines around closing headers
#        (e.g. 'else', 'catch', ...).
$BREAK-BLOCKS=<true | false | all>

# Break 'else if()' statements into two different lines.
$BREAK-ELSEIFS=<true / false>

# Add extra indentation entire blocks (including brackets).
$INDENT-BLOCKS=<true / false>

# Add extra indentation to '{' and '}' block brackets.
$INDENT-BRACKETS=<true / false>

# Indent 'case XXX:' lines, so that they are flush with
# their bodies.
$INDENT-CASES=<true / false>

# Indent 'class' blocks, so that the inner 'public:', 'protected:' and 'private:'
# headers are indented in relation to the class block.
$INDENT-CLASSES=<true / false>

# Indent labels so that they appear one indent less than the current indentation
# level, rather than being flushed completely to the left (which is the default).
$INDENT-LABELS=<true / false>

# Indent the contents of namespace blocks.
$INDENT-NAMESPACES=<true / false>

# Indent multi-line #define statements
INDENT-PREPROCESSOR=<true / false>

# Indent using <num> spaces per indent. Not specifying <num>  will result in a
# default  of 4 spacec per indent.
$INDENT-SPACES=<num>

# Indent 'switch' blocks, so that the inner 'case XXX:' headers are indented in
# relation to the switch block.
$INDENT-SWITCHES=<true / false>

# Indent a Java source file
$JAVA-STYLE=<true / false>

# Indent a maximal <num> spaces in a continuous statement, relatively to the
# previous line.
$MAX-INSTATEMENT-INDENT=<num>

# Indent a minimal <num> spaces in a continuous conditional belonging to a
# conditional header.
$MIN-CONDITIONAL-INDENT=<num>

# Surround symbols with whitespace:
# "paren": Insert space paddings around parenthesies only
# "oper":  Insert space paddings around operators only.
# "all":   Insert space paddings around operators AND parenthesies.
$PAD=<paren | oper | all>


Example:

# K&R indentation scheme
$indent-brackets=false
$indent-spaces=4
$brackets=attach
$indent-classes=false
$indent-switches=false
$indent-namespaces=false



8. WINDOWS EXPLORER INTEGRATION
--------------------------------------------------------------------------------

Create a link to WinHighlight.exe in the SendTo folder of your Windows home
directory. Now you can right-click your source files, and add them to the
Highlight file listbox during startup in the "Send to" pull down menu.


9. CONTACT:
--------------------------------------------------------------------------------

André Simon
andre.simon1@gmx.de
http://www.andre-simon.de/